home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / ems4c10.lzh / EMS4C.DOC < prev    next >
Text File  |  1993-08-07  |  44KB  |  1,322 lines
  1.  
  2.  
  3.                                    EMS Library
  4.  
  5.                                 For the C Language
  6.  
  7.  
  8.                                       (EMS4C)
  9.  
  10.  
  11.  
  12.                                  USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                   Version 1.0
  19.  
  20.                                  July 24, 1993
  21.  
  22.  
  23.  
  24.  
  25.                         This software is provided as-is.
  26.                  There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                               Copyright (C) 1993
  32.                               All rights reserved
  33.  
  34.  
  35.  
  36.                               MarshallSoft Computing, Inc.
  37.                               Post Office Box 4543
  38.                               Huntsville AL 35815
  39.  
  40.                               205-881-4630 Voice / FAX
  41.                               205-880-9748 Support BBS
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.         EMS4C Users Manual                                     Page 1
  61.                               C O N T E N T S
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          Chapter                                                   Page
  68.  
  69.          1.0 Introduction..............................................3
  70.              1.1 Distribution Files....................................3
  71.              1.2 Compiling the Library.................................4
  72.              1.3 User Support..........................................4
  73.              1.4 Installation..........................................5
  74.          2.0 MSDOS Memory..............................................6
  75.              2.1 Types of Memory.......................................6
  76.              2.2 Bank Switching........................................6
  77.          3.0 Example Programs..........................................7
  78.              3.1 EMS_TEST..............................................7
  79.              3.2 EMS_STAT..............................................7
  80.              3.3 The EMM4C Library.....................................7
  81.          4.0 EMS Library Functions.....................................8
  82.              4.1  emsLoaded............................................9
  83.              4.2  emsGetStatus.........................................9
  84.              4.3  emsGetFrame..........................................10
  85.              4.4  emsGetPages..........................................10
  86.              4.5  emsAllocate..........................................11
  87.              4.6  emsMapMemory.........................................12
  88.              4.7  emsRelease...........................................13
  89.              4.8  emsVersion...........................................13
  90.              4.9  emsSaveMap...........................................14
  91.              4.10 emsRestoreMap........................................14
  92.              4.11 emsGetHandles........................................15
  93.              4.12 emsOwnedPages........................................15
  94.              4.13 emsPageInfo..........................................16
  95.              4.14 emsError.............................................17
  96.          5.0 EMS4C Error Codes.........................................18
  97.          6.0 Legal Issues..............................................19
  98.              6.1 Registration..........................................19
  99.              6.2 Referral Program......................................19
  100.              6.3 License...............................................20
  101.              6.4 Warranty..............................................20
  102.          7.0 Revision History..........................................20
  103.          8.0 Other MarshallSoft Computing Products for C...............21
  104.              8.1 The Personal Communications Library for C.............21
  105.              8.2 The Personal Protocol Library for C...................21
  106.              8.3 The LZW Data Compression Library for C................22
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.         EMS4C Users Manual                                     Page 2
  121.          1.0 Introduction
  122.  
  123.          The   EMS4C   library   implements   version   3.2   of   the  LIM
  124.          (Lotus-Intel-Microsoft) specification for expanded memory. It will
  125.          run with either version 3.2 or 4.0 of the LIM specification.
  126.  
  127.          In  order  to  use  the EMS4C library, you must have either an EMS
  128.          memory board installed,  or  have  an  expanded  memory  emulation
  129.          driver program (such as EMM386 or 386MAX) installed.
  130.  
  131.          The  EMS4C  library  provides 14 functions which allow the user to
  132.          make use of expanded memory from their programs.  Several  example
  133.          programs are also provides such as:
  134.  
  135.          EMS_STAT : Displays EMS driver status.
  136.          EMS_TEST : EMS4C library test program.
  137.  
  138.          1.1 Distribution Files
  139.  
  140.          EMS4C.H      : EMS4C prototype file.
  141.          EMS4C_S.LIB  : EMS4C small model library.
  142.          EMS4C_L.LIB  : EMS4C large model library.
  143.          EMS4C_S.MIX  : MIX Power C small model object file.
  144.          EMS_ERR.C    : Error message file.
  145.          EMS_TEST.C   : Source code for the EMS4C test program.
  146.          EMS_TEST._T_ : Borland C & Turbo C makefile for EMS_TEST.
  147.          EMS_TEST._M_ : Microsoft C makefile for EMS_TEST.
  148.          EMS_TEST._Q_ : Microsoft Quick C makefile for EMS_TEST.
  149.          EMS_STAT.C   : Source code for the EMS4C status program.
  150.          EMS_STAT._T_ : Borland C & Turbo C makefile for EMS_TEST.
  151.          EMS_STAT._M_ : Microsoft C makefile for EMS_TEST.
  152.          EMS_STAT._Q_ : Microsoft Quick C makefile for EMS_TEST.
  153.  
  154.          Registered users also receive:
  155.  
  156.          EMS4C.ASM    : Source code for EMS4C library.
  157.          EMS4C_C.LIB  : EMS4C compact model library.
  158.          EMS4C_M.LIB  : EMS4C medium model library.
  159.          EMS4C_C.MIX  : MIX EMS4C compact model object.
  160.          EMS4C_L.MIX  : MIX EMS4C large model object.
  161.          MAKE_S.BAT   : Makes EMS4C_S.LIB from source.
  162.          MAKE_M.BAT   : Makes EMS4C_M.LIB from source.
  163.          MAKE_C.BAT   : Makes EMS4C_C.LIB from source.
  164.          MAKE_L.BAT   : Makes EMS4C_L.LIB from source.
  165.          MAKE_XS.BAT  : Makes EMS4C_S.MIX from source.
  166.          MAKE_XC.BAT  : Makes EMS4C_C.MIX from source.
  167.          MAKE_XL.BAT  : Makes EMS4C_L.MIX from source.
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.         EMS4C Users Manual                                     Page 3
  181.          1.2 Compiling the Library
  182.  
  183.  
  184.          The registered user can re-assemble the source code  (source  code
  185.          is  provided in the registered version only) for the library using
  186.          one of the provided batch files ( MAKE_S.BAT,  etc.).   Note  that
  187.          you will need a Microsoft compatible assembler such as MASM.EXE in
  188.          order to create new EMS library files.
  189.  
  190.          Makefiles  are  provided  for  re-assembling  the  libraries.  For
  191.          example, to create EMS4C_S.LIB, type:
  192.  
  193.                MAKE_S
  194.  
  195.  
  196.          1.3 User Support
  197.  
  198.  
  199.          We  want you to be successful in developing your application using
  200.          our libraries! We depend on our customers to let us know what they
  201.          need in a library.  This means we are committed to  providing  the
  202.          best  libraries  that  we  can.   If  you  have any suggestions or
  203.          comments, please write to us or give us a call.
  204.  
  205.          If  you  are having a problem using EMS4C or any of our libraries,
  206.          call (205) 881-4630 between 5 PM  and  9  PM  CST  Monday  through
  207.          Friday.  You can call at other times and leave a message, and call
  208.          back  later during our regular business hours for a reply. You can
  209.          also FAX us at this same number at any time.
  210.  
  211.          You  may  also  call our 24 hour BBS (2400 baud, no parity, 8 data
  212.          bits, 1 stop bit) at any time.  The BBS will  contain  the  latest
  213.          shareware version of EMS4C, messages, and other related files. All
  214.          files  are  in standard ZIP format. You can leave a message on the
  215.          BBS, and we will usually have a reply  ready  for  you  within  24
  216.          hours.   The dedicated telephone number is 205-880-9748.  Set your
  217.          modem for 1200 to 9600 baud, 8 data bits, no parity, one stop bit.
  218.  
  219.          The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is
  220.          published quarterly.  It discusses various communications problems
  221.          and  solutions using PCL4C (the communications library) as well as
  222.          related information such as data compression  issues.   Registered
  223.          users  receive  a  one  year complimentary subscription when first
  224.          registering and for each update purchased.   Additional  one  year
  225.          subscriptions  are  $15  plus $5 for overseas postage (postpaid in
  226.          the US).
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.         EMS4C Users Manual                                     Page 4
  241.          1.4 Installation
  242.  
  243.  
  244.          (1)  Microsoft C, Borland & Turbo C, and MIX Power C compilers are
  245.          supported. However, the code should work with most any C compiler.
  246.          Before installation of EMS4C, your C compiler  should  already  be
  247.          installed  on your system and tested. If you are not familiar with
  248.          makefiles, refer to your compiler manual. If  you  are  using  the
  249.          interactive environment for Quick C or Turbo C, be sure to compile
  250.          with the memory model corresponding to the EMS4C library used.
  251.  
  252.          (2) Make a backup  copy  of  your  distribution  disk.   Put  your
  253.          original distribution disk in a safe place.
  254.  
  255.          (3)  Create  a  work  directory  on  your work disk (normally your
  256.          harddisk). For example, to create a work directory named EMS4C, we
  257.          first log onto the work disk and then type:
  258.  
  259.                                MKDIR EMS4C
  260.  
  261.          (4)  Copy  all the files from your backup copy of the distribution
  262.          disk to your work directory.  For example, to  copy  from  the  A:
  263.          drive to your work directory, we type:
  264.  
  265.                               CD EMS4C
  266.                               COPY A:*.*
  267.  
  268.          (5)   Compile   EMS_STAT.C   and  EMS_TEST.C  and  link  with  the
  269.          appropriate EMS4C library For example, to make EMS_TEST.EXE:
  270.  
  271.              a) Borland Turbo C: Type
  272.  
  273.                   MAKE -fEMS_TEST._T_
  274.  
  275.              b) Microsoft C: Type
  276.  
  277.                   MAKE EMS_TEST._M_
  278.  
  279.              c) Quick C: Type
  280.  
  281.                   MAKE EMS_TEST._Q_
  282.  
  283.              d) MIX Power C: Type
  284.  
  285.                   X_TEST_T
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.         EMS4C Users Manual                                     Page 5
  301.          2.0 MSDOS Memory
  302.  
  303.          2.1 Types of Memory
  304.  
  305.          Your  system  can  have  three  kinds  of  memory:   Conventional,
  306.          extended, and expanded.
  307.  
  308.          All computers have "conventional" memory which includes all memory
  309.          up  to  640KB,  also known as "lower" DOS memory. The memory above
  310.          640KB to 1MB (1024KB) is known as "upper"  DOS  memory,  which  is
  311.          used  by  MSDOS  for  device  driver, video buffers, etc. Programs
  312.          running under MSDOS can address all memory up to 1MB.
  313.  
  314.          Extended  memory  is  available  on  80286 systems and up.  To use
  315.          extended memory, you must install an extended-memory manager  such
  316.          as  HIMEM.SYS  (distributed with MSDOS 5.0 & up).  Extended memory
  317.          can also be converted to expanded memory as explained below.
  318.  
  319.          The last type of memory on MSDOS  systems  is  "expanded"  memory.
  320.          Two  kinds  of  expanded  memory exists, both of which are handled
  321.          identically by EMS4C.  The first type of  expanded  memory  is  an
  322.          expanded memory board that you install in your computer.  Expanded
  323.          memory  boards  can  be installed in any IBM PC beginning with the
  324.          8088 processor. Refer to the directions that came with your board.
  325.  
  326.          The  second type of expanded memory is really extended memory that
  327.          has  been  converted  to  expanded  memory  by  a  expanded-memory
  328.          emulator such as EMM386 (distributed with MSDOS 5.0 & up), 386MAX,
  329.          etc.  Expanded  memory  created  from  extended  memory behaves in
  330.          exactly the same way as true expanded memory.
  331.  
  332.          2.1 Bank Switching
  333.  
  334.          Expanded  memory is implemented by a technique where more than 1MB
  335.          can be used by MSDOS programs, which are limited to addressing 1MB
  336.          of memory.  This is done by a technique called "bank switching" in
  337.          which up to 32MB (in EMS 4.0) can be  referenced  in  16KB  blocks
  338.          within the 1st 1MB of memory.
  339.  
  340.          The  expanded memory is organized into contiguous 16KB pages, which
  341.          can be mapped into any of four contiguous 16KB page frames located
  342.          somewhere between 640KB and 1024KB. The mapping is  controlled  by
  343.          the EMS driver using interrupt 67H.
  344.  
  345.          The EMS4C library provides the interface necessary to perform this
  346.          bank switching from within your C program.
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.         EMS4C Users Manual                                     Page 6
  361.          3.0 Example Programs
  362.  
  363.  
  364.          Two example programs are provided.  Each example program should be
  365.          compiled  with  the provided makefile.  These example programs are
  366.          meant to demonstrate various ways in  which  the  EMS  compression
  367.          library can be used.
  368.  
  369.          If you are using an integrated  compiler  environment  instead  of
  370.          makefiles,  notice  that  each  program is compiled with the SMALL
  371.          memory model.
  372.  
  373.          3.1 EMS_STAT
  374.  
  375.          EMS_STAT  will  display  all EMS parameters (such as the amount of
  376.          EMS memory available) on your system.
  377.  
  378.          To run EMS_STAT, just type:
  379.  
  380.              EMS_STAT
  381.  
  382.          3.2 EMS_TEST
  383.  
  384.          The EMS_TEST program tests each of the  EMS4C  library  functions.
  385.          The  program  also  exercises  the memory mapping calls, verifying
  386.          that all mapping is performed without data loss.
  387.  
  388.          To run EMS_TEST, just type:
  389.  
  390.             EMS_TEST
  391.  
  392.          3.3 The EMM4C Library
  393.  
  394.          The EMM4C (Expanded Memory  Manager  for  C  Library)  library  is
  395.          provided  as a final example of using the EMS4C library. The EMM4C
  396.          library implements memory allocation and  de-allocation  functions
  397.          for  EMS  memory  similiar  to  the  standard  C  runtime  library
  398.          functions malloc() and free().
  399.  
  400.          There is also a EMM4C test driver provided with the EMM4C  library
  401.          that   exercises  the  EMM4C  functions.  The  EMM4C  test  driver
  402.          (EMM_TEST) operates similiarly to the EMS4C test driver.
  403.  
  404.          The  EMM4C  library  is  documented  in  the  EMM4C.DOC  file.   A
  405.          registered  version of the EMM4C library is provided when the user
  406.          registers the EMS4C library.
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.         EMS4C Users Manual                                     Page 7
  421.          4.0 EMS Library Functions
  422.  
  423.  
  424.          There are 14 functions in the EMS4C library.
  425.  
  426.          emsLoaded      Verifies that an expanded memory driver is loaded.
  427.          emsGetStatus   Verifies that EMS hardware (if installed) is OK.
  428.          emsGetFrame    Returns the address of the 1st EMS frame.
  429.          emsGetPages    Gets the # free pages & the total # pages.
  430.          emsAllocate    Allocates requested EMS pages.
  431.          emsMapMemory   Maps an EMS page to a page frame.
  432.          emsRelease     Release previously allocated EMS pages.
  433.          emsVersion     Gets EMS driver (EMM) version.
  434.          emsSaveMap     Saves EMS mapping context.
  435.          emsRestoreMap  Restores a previous saved EMS mapping context.
  436.          emsGetHandles  Get number of active EMS handles.
  437.          emsOwnedPages  Returns the number of pages owned by a handle.
  438.          emsPageInfo    Returns handles & pages for all handles.
  439.          emsPageMap     Gets or sets EMS page-mapping registers.
  440.  
  441.          All  error  codes  returned by EMS4C are those returned by the EMS
  442.          driver, except for error codes 0xA0, 0xA1, and 0xA2.
  443.  
  444.          This library should only be used with  EMS  version  3.2  or  4.0.
  445.          Earlier versions of the EMS may not work properly.
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.         EMS4C Users Manual                                     Page 8
  481.                              4.1 emsLoaded
  482.  
  483.  
  484.         Function:    Verifies that an expanded memory driver is loaded.
  485.  
  486.           Syntax:    int emsLoaded(void);
  487.  
  488.           Remarks:   You must  call  emsLoaded  before  any  other  EMS4C
  489.                      function  in order to verify that an expanded-memory
  490.                      driver is loaded.
  491.  
  492.          Returns:    0   : No error.
  493.                      0xa0: EMS driver not loaded.
  494.                      0xa1: Illegal library modification. (Shareware only).
  495.  
  496.           Example:      /* is EMS driver loaded ? */
  497.                        Code = emsLoaded();
  498.                        if( Code != 0 )
  499.                            {/* error returned ! */
  500.                             printf("emsLoaded returns %x\n",Code);
  501.                             ...
  502.                            }
  503.  
  504.          See Also    emsGetStatus
  505.  
  506.  
  507.                              4.2 emsGetStatus
  508.  
  509.  
  510.         Function:    Verifies that EMS hardware (if installed) is OK.
  511.  
  512.           Syntax:    int emsGetStatus(void);
  513.  
  514.          Remarks:    The   emsGetStatus()   function   should  be  called
  515.                      immediately after call emsLoaded().
  516.  
  517.          Returns:    0x00: No error.
  518.                      0x80: Internal error in EMS software.
  519.                      0x81: Malfunction in EMS hardware.
  520.                      0x84: Undefined function.
  521.  
  522.          Example:    /* check EMS driver status */
  523.                      Code = emsGetStatus();
  524.                      if( Code != 0 )
  525.                         {/* error returned ! */
  526.                          printf("emsGetStatus returns %x\n",Code);
  527.                          ...
  528.                         }
  529.  
  530.          See Also    emsLoaded.
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.         EMS4C Users Manual                                     Page 9
  541.                              4.3 emsGetFrame
  542.  
  543.  
  544.         Function:  Returns the address of the 1st EMS frame.
  545.  
  546.           Syntax:  int emsGetFrame(SegmentP)
  547.                        int *SegmentP;    /* pointer to segment of page frame */
  548.  
  549.          Remarks:    The emsGetFrame() function is used to get the  segment
  550.                      address  of the first page frame. The four page frames
  551.                      are all 16KB  (16,384)  bytes  in  length  and  occupy
  552.                      contigous space in the area between 640KB and 1MB.
  553.  
  554.          Returns:    0x00: No error.
  555.                      0x80: Internal error in EMS software.
  556.                      0x81: Malfunction in EMS hardware.
  557.                      0x84: Undefined function.
  558.  
  559.          Example:    /* get the frame segment */
  560.                      int SegmentP;
  561.                      Code := emsGetFrame(&SegmentP);
  562.                      printf("Frame 0 address is at %x:0000\n",SegmentP);
  563.  
  564.  
  565.                              4.4 emsGetPages
  566.  
  567.  
  568.         Function:    Gets the # free pages & the total # pages.
  569.  
  570.           Syntax:    int emsGetPages(FreePagesP,TotalPagesP)
  571.                      int *FreePagesP;   /* pointer to # of free pages */
  572.                      int *TotalPagesP;  /* pointer to # of total pages */
  573.  
  574.          Remarks:     The  emsGetPages  function gets the nummber of system
  575.                      wide unallocated (free)  pages,  and  also  the  total
  576.                      number of pages. You may subsequently allocate no more
  577.                      than  the  number  of  free  pages  reported  by  this
  578.                      function.
  579.  
  580.          Returns:    0x00: No error.
  581.                      0x80: Internal error in EMS software.
  582.                      0x81: Malfunction in EMS hardware.
  583.                      0x84: Undefined function.
  584.  
  585.          Example:    /* get  # free and total pages */
  586.                      int Code;
  587.                      int FreePages;
  588.                      int TotalPages;
  589.                      ...
  590.                      Code = emsGetPages(&FreePages,&TotalPages);
  591.  
  592.          See Also    emsAllocate
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.         EMS4C Users Manual                                     Page 10
  601.                              4.5 emsAllocate
  602.  
  603.  
  604.         Function:    Allocates requested EMS pages.
  605.  
  606.           Syntax:    int emsAllocate(NumberPages,HandleP)
  607.                      int NumberPages;  /* number of pages to allocate */
  608.                      int *HandleP;     /* pointer to handle */
  609.  
  610.          Remarks:    The emsAllocated function  attempts  to  allocate  the
  611.                      requested  number  of pages, which must be less tna or
  612.                      equal to  the  number  of  free  pages  as  return  by
  613.                      emsGetPages.  The  Handle  (returned) must be used for
  614.                      subsequent calls to the remaining EMS functions.
  615.  
  616.          Returns:    0x00: No error.
  617.                      0x80: Internal error in EMS software.
  618.                      0x81: Malfunction in EMS hardware.
  619.                      0x84: Undefined function.
  620.                      0x85: No more handles available.
  621.                      0x87: Logical pages not available.
  622.                      0x88: Logical pages not currently available.
  623.                      0x89: Zero pages requested.
  624.  
  625.          Example:    /* get  # free and total pages */
  626.                      int Code;
  627.                      int NumberPages;
  628.                      int Handle;
  629.                      ...
  630.                      Code = emsAllocate(&NumberPages,&Handle);
  631.  
  632.          See Also    emsGetPages, emsRelease.
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.         EMS4C Users Manual                                     Page 11
  661.                              4.6 emsMapMemory
  662.  
  663.  
  664.         Function:    Maps an EMS page to a page frame.
  665.  
  666.           Syntax:    int emsMapMemory(PhysicalPage,LogicalPage,Handle)
  667.                      int PhysicalPage;    /* Physical page (frame) number (0-3) */
  668.                      int LogicalPage;     /* Logical page number */
  669.                      int Handle;          /* EMS handle */
  670.  
  671.          Remarks:    The emsMapMemory function maps the requested  page  to
  672.                      the  the  requested  frame.  Once  the  page  has been
  673.                      successfully mapped, you may address the  contents  of
  674.                      the page at the frame addresss.
  675.  
  676.          Returns:    0x00: No error.
  677.                      0x80: Internal error in EMS software.
  678.                      0x81: Malfunction in EMS hardware.
  679.                      0x83: Invalid handle.
  680.                      0x84: Undefined function.
  681.                      0x8a: Logical page not assigned to this handle.
  682.                      0x8b: Physical page number invalid.
  683.  
  684.          Example:    /* map memory */
  685.                      int Page;
  686.                      int Frame;
  687.                      int Handle;
  688.                      ...
  689.                      Code = emsMapMemory(Page,Frame,Handle);
  690.  
  691.          See Also    emsAllocate().
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.         EMS4C Users Manual                                     Page 12
  721.                              4.7 emsRelease
  722.  
  723.  
  724.         Function:    Release previously allocated EMS pages.
  725.  
  726.           Syntax:    int emsRelease(Handle)
  727.                      int Handle;          /* EMS handle */
  728.  
  729.          Remarks:    The  emsRelease  function  releases memory previously
  730.                      allocated with emsAllocate(). Once memory is released,
  731.                      you can no longer reference it through the page frame.
  732.  
  733.          Returns:    0x00: No error.
  734.                      0x80: Internal error in EMS software.
  735.                      0x81: Malfunction in EMS hardware.
  736.                      0x83: Invalid handle.
  737.                      0x84: Undefined function.
  738.                      0x86: Error in mapping context.
  739.  
  740.          Example:    /* release memory */
  741.                      int Handle;
  742.                      ...
  743.                      Code = emsRelease(Handle);
  744.  
  745.          See Also    emsAllocate().
  746.  
  747.  
  748.                              4.8 emsVersion
  749.  
  750.  
  751.         Function:    Gets EMS driver (EMM) version.
  752.  
  753.           Syntax:    int emsVersion(VersionP)
  754.                      int *Version;       /* pointer to version number */
  755.  
  756.          Remarks:    The emsVersion function  returns the  Expanded  Memory
  757.                      Manager (EMM). The EMS4C library supports versions 3.2
  758.                      and 4.0 (the two most recent as of this date).
  759.  
  760.          Returns:    0x00: No error.
  761.                      0x80: Internal error in EMS software.
  762.                      0x81: Malfunction in EMS hardware.
  763.                      0x84: Undefined function.
  764.  
  765.          Example:    /* get EMM version # */
  766.                      int Version;
  767.                      int Code;
  768.                      Code = emsVersion(&Version);
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.         EMS4C Users Manual                                     Page 13
  781.                              4.9 emsSaveMap
  782.  
  783.  
  784.         Function:    Saves EMS mapping context.
  785.  
  786.           Syntax:    int emsSaveMap(Handle)
  787.                      int Handle;          /* EMS handle */
  788.  
  789.          Remarks:     The emsSaveMap function saves the current EMS mapping
  790.                      context. You will only need to call this  function  if
  791.                      you  are  writing  a  memory resident (TSR)program, an
  792.                      interrupt service routine  (ISR),  device  driver,  or
  793.                      other  code that will have to share the EMS with other
  794.                      programs at runtime.
  795.  
  796.          Returns:    0x00: No error.
  797.                      0x80: Internal error in EMS software.
  798.                      0x81: Malfunction in EMS hardware.
  799.                      0x83: Invalid handle.
  800.                      0x84: Undefined function.
  801.                      0x8c: Page-mapping hardware state save area full.
  802.                      0x8d: Mapping context already associated.
  803.  
  804.          Example:    /* save mapping context */
  805.                      int Handle;
  806.                      int Code;
  807.                      Code = emsSaveMap(Handle);
  808.  
  809.          See Also    emsRestoreMap
  810.  
  811.  
  812.                              4.10 emsRestoreMap
  813.  
  814.  
  815.         Function:    Restores a previous saved EMS mapping context.
  816.  
  817.           Syntax:    int emsRestoreMap(Handle)
  818.                      int Handle;          /* EMS handle */
  819.  
  820.          Remarks:    The emsRestoreMap() function  restores  the  mapping
  821.                      context  previously saved with emsSaveMap(). Note that
  822.                      at most one mapping context can be saved  at  any  one
  823.                      time. Refer to the emsSaveMap() function.
  824.  
  825.          Returns:    0x00: No error.
  826.                      0x80: Internal error in EMS software.
  827.                      0x81: Malfunction in EMS hardware.
  828.                      0x83: Invalid handle.
  829.                      0x84: Undefined function.
  830.                      0x8e: Save area has no context for handle.
  831.  
  832.          Example:    /* restore mapping context */
  833.                      int Handle;
  834.                      int Code;
  835.                      Code = emsRestoreMap(Handle);
  836.  
  837.          See Also    emsSaveMap
  838.  
  839.  
  840.         EMS4C Users Manual                                     Page 14
  841.                              4.11 emsActiveHandles
  842.  
  843.         Function:    Get number of active EMS handles.
  844.  
  845.           Syntax:    int emsActiveHandles(HandlesP)
  846.                      int *HandlesP;     /* pointer to number of handles */
  847.  
  848.          Remarks:     The  emsActiveHandles()  function  gets the number of
  849.                      active  EMS  handles  already  allocated.  If   0   is
  850.                      reported,  then  EMS  is not in use. There is a system
  851.                      wide maximum of 255 handles.
  852.  
  853.          Returns:    0x00: No error.
  854.                      0x80: Internal error in EMS software.
  855.                      0x81: Malfunction in EMS hardware.
  856.                      0x83: Invalid handle.
  857.                      0x84: Undefined function.
  858.  
  859.          Example:    /* report # free EMS handles */
  860.                      int Code;
  861.                      int Handles;
  862.                      Code = emsActiveHandles(&Handles);
  863.                      if(Handles>0)printf("%d free handles\n",255-Handles);
  864.  
  865.          See Also    emsOwnedPages
  866.  
  867.  
  868.                              4.12 emsOwnedPages
  869.  
  870.  
  871.         Function:    Returns the number of pages owned by a handle.
  872.  
  873.           Syntax:    int emsOwnedPages(Handle,OwnedP)
  874.                      int Handle;     /* EMS handle */
  875.                      int OwnedP;     /* pointer to owned handles */
  876.  
  877.          Remarks:     The  emsOwnedPages()  function  gets  the  number  of
  878.                      handles owned by the specified EMS handle. The minimum
  879.                      value is one.
  880.  
  881.          Returns:    0x00: No error.
  882.                      0x80: Internal error in EMS software.
  883.                      0x81: Malfunction in EMS hardware.
  884.                      0x83: Invalid handle.
  885.                      0x84: Undefined function.
  886.  
  887.          Example:    /* report # owned pages */
  888.                      int Code;
  889.                      int Owned;
  890.                      int Handle;
  891.                      ...
  892.                      Code = emsOwnedPages(Handle,&Owned);
  893.                      printf("%d pages owned by handle %d\n",Owned);
  894.  
  895.          See Also    emsActiveHandles
  896.  
  897.  
  898.  
  899.  
  900.         EMS4C Users Manual                                     Page 15
  901.                              4.13 emsPageInfo
  902.  
  903.         Function:    Returns handles & pages for all handles
  904.  
  905.           Syntax:    int emsPageInfo(PagesP,ActiveP)
  906.                      int *PagesP;       /* pointer to array to hold info */
  907.                      int *ActiveP;      /* pointer to # active pages */
  908.  
  909.          Remarks:    The emsPageInfo() function fills a passed  array  with
  910.                      4-byte  entries  of  handles & page counts: Bytes 0 &1
  911.                      contain the EMS handle, while bytes 2 & 3 contain  the
  912.                      number   of  pages.  Be  sure  to  pass  an  array  of
  913.                      sufficient size to contain all  entries.
  914.  
  915.          Returns:    0x00: No error.
  916.                      0x80: Internal error in EMS software.
  917.                      0x81: Malfunction in EMS hardware.
  918.                      0x84: Undefined function.
  919.  
  920.          Example:    /* get page info */
  921.                      int Code;
  922.                      int Active;
  923.                      struct
  924.                      {int Handle;
  925.                       int Pages;
  926.                      } Array[255];
  927.                      ...
  928.                      Code = emsPageInfo(&Array,&Active);
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.         EMS4C Users Manual                                     Page 16
  961.                              4.14 emsPageMap
  962.  
  963.  
  964.         Function:    Gets or sets EMS page-mapping registers.
  965.  
  966.           Syntax:    int emsPageMap(Function,SrcArray,DstArray,*Result)
  967.                      int Function;        /* sub-function */
  968.                      char SrcArray[];     /* pointer to source array */
  969.                      char DstArray[];     /* pointer to dest. array */
  970.                      int  *Result;        /* pointer to Result */
  971.  
  972.          Remarks:    The emsPageMap function is used to get or set page map
  973.                      registers, or get the size of the Page Map array. This
  974.                      function is  designed  to  support  multi-tasking  DOS
  975.                      extenders such as Windows.
  976.  
  977.                      The  Result  variable  will contain the page map array
  978.                      size  if  emsPageMap  was  called  successfully   with
  979.                      sub-function 3.
  980.  
  981.                      The  emsPageMap  function  should  not  be  used   for
  982.                      programs  other  than multi-tasking Operating Systems.
  983.                      It is included in the EMS4C library  for  completeness
  984.                      only.
  985.  
  986.                        Subfunction values are:
  987.  
  988.                        00H = Getting registers into array
  989.                        01H = Setting registers from array
  990.                        02H = Get and set operation
  991.                        03H = Return size of page-mapping array
  992.  
  993.          Returns:    0x00: No error.
  994.                      0x80: Internal error in EMS software.
  995.                      0x81: Malfunction in EMS hardware.
  996.                      0x84: Undefined function.
  997.                      0x8f: Subfunction not defined.
  998.  
  999.          Example:    /* get size of page mapping array */
  1000.                      char SrcArray[], DstArray[];
  1001.                      int Result;
  1002.                      ...
  1003.                      Code = emsPageMap(3,SrcArray,DstArray,&Result);
  1004.                      if(Code==0) printf("Array size = %d\n",Result);
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.         EMS4C Users Manual                                     Page 17
  1021.          5.0 EMS Error Codes
  1022.  
  1023.  
  1024.          Be  sure and check the return codes from each EMS4C function call.
  1025.          There are 18 error codes returned by the EMS4C library other  than
  1026.          0  (no  error).   All  error  codes  are  negative numbers.  Their
  1027.          numerical values are the same  as  returned  from  the  MSDOS  EMS
  1028.          Driver (EMMXXXX0) and are defined in the EMS4C.H file.
  1029.  
  1030.                              EMS Error Codes
  1031.  
  1032.          **************************************************************
  1033.          *  0x00  *  No error.                                        *
  1034.          *  0x80  *  Internal error in EMS software.                  *
  1035.          *  0x81  *  Malfunction in EMS hardware.                     *
  1036.          *  0x83  *  Invalid handle.                                  *
  1037.          *  0x84  *  Undefined function.                              *
  1038.          *  0x85  *  No more handles available.                       *
  1039.          *  0x86  *  Error in mapping context.                        *
  1040.          *  0x87  *  Logical pages not available.                     *
  1041.          *  0x88  *  Logical pages not currently available.           *
  1042.          *  0x89  *  Zero pages requested.                            *
  1043.          *  0x8a  *  Logical page not assigned to this handle.        *
  1044.          *  0x8b  *  Physical page number invalid.                    *
  1045.          *  0x8c  *  Page-mapping hardware state save area full.      *
  1046.          *  0x8d  *  Mapping context already associated.              *
  1047.          *  0x8e  *  Save area has no context for handle.             *
  1048.          *  0x8f  *  Subfunction not defined.                         *
  1049.          *  0xa0  *  EMS driven not loaded.                           *
  1050.          *  0xa1  *  Illegal library modification. (Shareware only).  *
  1051.          *  0xa2  *  emsLoaded not called.                            *
  1052.          **************************************************************
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.         EMS4C Users Manual                                     Page 18
  1081.          6.0 Legal Issues
  1082.  
  1083.          6.1 Registration
  1084.  
  1085.  
  1086.          If you wish to register the EMS4C library, please send $35 plus $3
  1087.          S&H ($6 outside of North America) to:
  1088.  
  1089.                   MarshallSoft Computing, Inc.
  1090.                   Post Office Box  4543
  1091.                   Huntsville AL 35815
  1092.  
  1093.          We  accept  American  Express  (account  number,  expiration date,
  1094.          exact name  on  your  card,  and  complete  AmEx  billing  address
  1095.          required),  checks  in  US  dollars  drawn  on a US bank, purchase
  1096.          orders (POs) from recognized US schools and  companies  listed  in
  1097.          Dun  &  Bradstreet,  and  COD  (street  address  and  phone number
  1098.          required) within the USA (plus a $3 COD charge).  Print  the  file
  1099.          EMS4C.INV if an invoice is needed.
  1100.  
  1101.          You  can  also  order EMS4C from The Public Software Library (PSL)
  1102.          with your MC, Visa, AmEx, or Discover card by calling 800-242-4PSL
  1103.          (from overseas: 713-524-6394) or by  FAX  at  713-524-6398  or  by
  1104.          CompuServe  at  [71355,470].  THESE NUMBERS ARE FOR ORDERING ONLY.
  1105.          The product number for EMS4C is 10912.
  1106.  
  1107.          If  you  wish  to  update from an older version of EMS4C, send $15
  1108.          plus  $3  S&H  ($6 outside  of  North  America).  Updates  must be
  1109.          ordered directly from MarshallSoft Computing.
  1110.  
  1111.          The registered package includes:
  1112.  
  1113.          o  No shareware screen.
  1114.          o  Assembler source code for the library.
  1115.          o  Laser printed Users Manual.
  1116.          o  Telephone / FAX / BBS support for one year.
  1117.          o  The EMM4C library.
  1118.  
  1119.          Print  the  file EMS4C.INV if an invoice is needed. The registered
  1120.          user will receive the latest version of EMS4C shipped by  two  day
  1121.          priority  mail  (packet  airmail  overseas).   A 5.25" diskette is
  1122.          provided unless a 3.5" diskette is requested.
  1123.  
  1124.  
  1125.          6.2 Referral Program
  1126.  
  1127.  
  1128.          The registered user will receive  a  $5  certificate  towards  any
  1129.          MarshallSoft   Computing  product  by  referring  a  new  customer
  1130.          (someone who has never registered with us). The new customer  must
  1131.          identify  you at the time the order is placed.  You will be mailed
  1132.          a certificate worth $5 when the new registration is paid.
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.         EMS4C Users Manual                                     Page 19
  1141.          6.3 License
  1142.  
  1143.  
  1144.          MarshallSoft Computing, Inc. grants the registered user  of  EMS4C
  1145.          the  right  to  use  the  EMS4C  library  (in  object form) in the
  1146.          development  of  any  software  product  without  any   royalties.
  1147.          However,   the   source   code  (EMS4C.ASM)  for  the  library  is
  1148.          copyrighted by  MarshallSoft  Computing,  Inc.,  and  may  not  be
  1149.          released in whole or in part.
  1150.  
  1151.  
  1152.          6.4 Warranty
  1153.  
  1154.  
  1155.          MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING  TO
  1156.          THIS  SOFTWARE,  WHETHER  EXPRESSED  OR IMPLIED, INCLUDING BUT NOT
  1157.          LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY  AND  FITNESS
  1158.          FOR  A  PARTICULAR  PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
  1159.          AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING,  INC.
  1160.          NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
  1161.          OR  DELIVERY  OF  THIS  SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  1162.  
  1163.          CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1164.          INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
  1165.          INC.  HAS BEEN ADVISED OF  THE  POSSIBILITY  OF  SUCH  DAMAGES  OR
  1166.          CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
  1167.          FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
  1168.          USE  THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
  1169.          USING  THE  SOFTWARE  BEARS  ALL  RISK  AS  TO  THE  QUALITY   AND
  1170.          PERFORMANCE OF THE SOFTWARE.
  1171.  
  1172.          Some  states  do not allow the exclusion of the limit of liability
  1173.          for consequential or incidental damages, so the  above  limitation
  1174.          may not apply to you.
  1175.  
  1176.          This  agreement  shall  be  governed  by  the laws of the State of
  1177.          Alabama and shall inure to the benefit of Marshallsoft  Computing,
  1178.          Inc.   and  any successors, administrators, heirs and assigns. Any
  1179.          action or proceeding brought by either  party  against  the  other
  1180.          arising  out of or related to this agreement shall be brought only
  1181.          in a STATE or FEDERAL COURT of competent jurisdiction  located  in
  1182.          Madison County, Alabama. The parties hereby consent to in personam
  1183.          jurisdiction of said courts.
  1184.  
  1185.  
  1186.          7.0 Revision History
  1187.  
  1188.  
  1189.          Version 1.0 -- July 24, 1993 -- original release.
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.         EMS4C Users Manual                                     Page 20
  1201.          8.0 Other MarshallSoft Computing Products for C
  1202.  
  1203.  
  1204.          Shareware  versions  of  all  MarshallSoft  Computing products are
  1205.          available on our user support BBS 205-880-9748.
  1206.  
  1207.  
  1208.          8.1 The Personal Communications Library for C
  1209.  
  1210.  
  1211.          The Personal Communications Library for the C Language (PCL4C)  is
  1212.          an  asynchronous  communications  library designed for experienced
  1213.          software  developers  programming  in  C.   Four   compilers   are
  1214.          supported:  Microsoft  Optimizing  C,  Microsoft  Quick C, Borland
  1215.          Turbo C, and MIX Power  C.   An  IBM  PC/XT/AT  or  compatible  is
  1216.          required.  The PCL features:
  1217.  
  1218.          o SMALL, COMPACT, MEDIUM & LARGE memory models.
  1219.          o 33 communications and support functions.
  1220.          o Supports PC/4 and PC/8 Digiboard.
  1221.          o Support for the high performance INS16550 UART.
  1222.          o Supports hardware (RTS/CTS) flow control.
  1223.          o Interrupt driven receiver.
  1224.          o Supports 300 baud to 115,200 baud.
  1225.          o Supports COM1, COM2, COM3, and  COM4.
  1226.          o Adjustable receive queues from 8 bytes to 32 KB.
  1227.          o Control-BREAK error exit.
  1228.          o 17 communications error conditions trapped.
  1229.          o Allows 4 ports to run concurrently.
  1230.          o Complete modem control & status.
  1231.          o Written in assembly language for small size & high speed.
  1232.          o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
  1233.  
  1234.          The Personal Communications Library for C (PCL4C) is available for
  1235.          $55  plus  $3 S&H ($6 S&H overseas). It may be ordered at the same
  1236.          time as the Personal Protocol Library for $65 plus $3.50  S&H  ($7
  1237.          overseas).
  1238.  
  1239.  
  1240.          8.2 The Personal Protocol Library for C
  1241.  
  1242.  
  1243.          The  Personal  Protocol  Library  (PPL)  consist of a state driven
  1244.          library  which  implements  the  XMODEM,  XMODEM-CRC,   XMODEM-1K,
  1245.          XMODEM-G,  YMODEM,  and  YMODEM-G  file  transfer protocols.  This
  1246.          allows  the  programmer  to  run   multiple   protocol   transfers
  1247.          simultaneously while interacting with the user at the keyboard.
  1248.  
  1249.          The  Personal  Protocol Library for C (PPL4C) is available for $35
  1250.          plus $3 S&H ($6 S&H overseas). Both the Communications library and
  1251.          the Protocol library can be ordered together for $65.
  1252.  
  1253.          The PPL requires the Personal Protocol Library for  C  (PCL4C)  as
  1254.          described above.
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.         EMS4C Users Manual                                     Page 21
  1261.          8.3 The LZW Data Compression Library for C
  1262.  
  1263.          LZW4C is an implementation of the LZW (Lempel-Ziv-Welch) algorithm
  1264.          for compressing and decompressing  data.   LZW  does  particularly
  1265.          well on text files, achieving better than a 50 % compression ratio
  1266.          for many files.
  1267.  
  1268.          The  LZW  algorithm  is  considered  to be one of the best general
  1269.          purpose algorithms available today.  The  new  high  speed  modems
  1270.          that  employ  on-the-fly  data  compression (such as MNP 5.0 & the
  1271.          V.42 bis international standard) use the LZW algorithm, as well as
  1272.          such well known utility programs such as PKZIP.
  1273.  
  1274.          The  LZW  Data Compression Library for C is available for $35 plus
  1275.          $3 S&H ($6 S&H overseas).
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.         EMS4C Users Manual                                     Page 22
  1321.  
  1322.